---
title: 'GitHub Integration | Cypress Documentation'
description: 'Configure GitHub status checks and pull request comments to show Cypress test results from Cypress Cloud.'
sidebar_position: 10
sidebar_label: GitHub
---

<ProductHeading product="cloud" />

# GitHub Integration

:::info

##### <Icon name="question-circle" color="#4BBFD2" /> What you'll learn

- How to install the Cypress GitHub App
- How to enable GitHub integration for a project
- How to configure status checks and pull request comments

:::

[Cypress Cloud](https://on.cypress.io/cloud) can integrate your Cypress tests
with your GitHub workflow via commit [status checks](#Status-checks) and
[pull request comments](#Pull-request-comments). A project first needs to be
[set up to record](/cloud/account-management/projects) to Cypress Cloud
to use GitHub integration.

<DocsImage
  src="/img/cloud/integrations/github/pull-request-cypress-integration-comments-github-checks.jpg"
  alt="Cypress GitHub App PR"
  width={800}
/>

:::caution

<Icon name="exclamation-triangle" /> The user enabling the integration must be a
GitHub admin to enable repository access.

:::

:::caution

GitHub Integration depends on your CI environment reliably providing a commit
SHA (typically via an environment variable). This is not a problem for most
users, but if you are facing GitHub integration issues with your CI setup,
please make sure the git information is being sent properly by following
[these guidelines](/app/continuous-integration/overview#Git-information).
If you still face issues after this, please
[contact us](mailto:hello@cypress.io).

:::

## GitHub Enterprise

:::tip

<Icon name="star" /> **Premium Cypress Cloud Feature**

GitHub Enterprise integration is included in our
[Business and Enterprise paid pricing plans](https://www.cypress.io/pricing).

:::

To configure Cypress Cloud integration for your GitHub Enterprise site, first
follow the instructions to
[install via organization integration settings](#Install-via-organization-integration-settings)
below, then skip to
[Cypress GitHub Enterprise app installation](#Cypress-GitHub-Enterprise-app-installation-process),
and finally
[enable the integration for a project](#Enabling-GitHub-integration-for-a-project).

## Install the Cypress GitHub app

Before enabling GitHub integration for your Cypress projects, you must first
install the Cypress GitHub App. You can start the GitHub App installation
process via your organization's settings page or a project's settings page in
[Cypress Cloud](https://on.cypress.io/cloud).

### Install via organization integration settings

1. Go to Cypress Cloud
   [Organizations page](https://cloud.cypress.io/organizations) or open the
   organization switcher.
2. Select the organization you wish to integrate with a GitHub account or GitHub
   organization.

   <DocsImage
     src="/img/cloud/organizations/select-cypress-organization.jpg"
     alt="Select an organization"
     width={600}
   />

3. Visit the selected organization's **Integrations** page via the side
   navigation.

   <DocsImage
     src="/img/cloud/organizations/navigate-to-organization-integrations.jpg"
     alt="Install Cypress GitHub from Integrations"
     width={600}
   />

4. Click the **Install GitHub Integration** or **Install GitHub Enterprise
   Integration** button.

### Install via project settings

:::caution

This installation method does not apply to GitHub Enterprise.

:::

1. Select your organization in the organization switcher.

   <DocsImage
     src="/img/cloud/organizations/select-cypress-organization.jpg"
     alt="Select an organization"
     width={600}
   />

2. Select the project you wish to integrate with a GitHub repository.

   <DocsImage
     src="/img/cloud/projects/select-cypress-project.jpg"
     alt="Select a project"
   />

3. Go to the project's settings page.

   <DocsImage
     src="/img/cloud/projects/select-project-settings.jpg"
     alt="Visit project settings"
     width={600}
   />

4. Scroll down to the **GitHub Integration** section.
5. Click the **Enable GitHub** button.

   <DocsImage
     src="/img/cloud/integrations/github/enable-github.jpg"
     alt="Enable GitHub"
   />

### Cypress GitHub app installation process

Once you've started the GitHub App installation process
[via a Cypress organization's settings](#Install-via-organization-integration-settings)
or [a project's settings](#Install-via-project-settings), you will be directed
to GitHub.com to complete the installation:

1. Select the desired GitHub organization or account to integrate with your
   Cypress Cloud organization.

   <DocsImage
     src="/img/cloud/integrations/github/select-gh-org.jpg"
     alt="Select a GitHub organization"
   />

2. Choose which repositories to associate with the Cypress GitHub App. You can
   choose **All repositories** or **Only select repositories**. with your
   Cypress GitHub App installation.

:::info

All current and _future_ repositories will be included with this installation if
you choose **All repositories**.

:::

<DocsImage
  src="/img/cloud/integrations/github/select-gh-repos.jpg"
  alt="Select GitHub repositories"
  width={600}
/>

3. Click the **Install** button to complete the installation.

:::warning

If you are running the tests from within a restrictive VPN, see
[which subdomains to add to your allowlist for Cypress Cloud and your GitHub integration to work properly](/cloud/faq#Im-working-with-a-restrictive-VPN-Which-subdomains-do-I-have-to-allow-on-my-VPN-for-Cypress-Cloud-to-work-properly)

:::

### Cypress GitHub Enterprise app installation process

To integrate Cypress Cloud with GitHub Enterprise, you need to create a new
GitHub App, copy the necessary settings and credentials from the new app, paste
them into Cypress Cloud, and complete the activation process.

1. With your Cypress Cloud organization's GitHub Enterprise page open, open a
   new tab or browser window and browse to your GitHub Enterprise site. Navigate
   to your GitHub organization → **Settings** → **Developer settings** →
   **GitHub Apps**. Do **NOT** go to **OAuth Apps**. Click the **New GitHub
   App** button.

<DocsImage
  src="/img/cloud/integrations/github/ghe/ghe-01.jpg"
  alt="Create new GitHub App"
/>

2. Complete the **Register new GitHub app** section.
   - Enter a **GitHub App name**. Name may contain only dashes, letters, and
     numbers, **no spaces**.
   - Enter Cypress Cloud **Homepage URL**, https://cloud.cypress.io
   - Enter the **Callback URL** and **Setup URL**,
     https://cloud.cypress.io/apps/github/callback

<DocsImage
  src="/img/cloud/integrations/github/ghe/ghe-02.jpg"
  alt="Configure new GitHub App"
  width={650}
/>

3. Complete the **Webhook** section.
   - Enter the **Webhook URL**, https://cloud.cypress.io/webhooks/github-app
   - Copy and paste the provided **Webhook secret** from Cypress Cloud to
     **Webhook secret (optional)**.

<DocsImage
  src="/img/cloud/integrations/github/ghe/ghe-03.jpg"
  alt="Configure app webhook"
  width={650}
/>

4. Set the **Repository Permissions**. Below are the minimum permissions
   required for the new GitHub App.
   - **Pull requests**: read & write
   - **Commit statuses**: read & write

<DocsImage
  src="/img/cloud/integrations/github/ghe/ghe-04-commit.jpg"
  alt="Configure app permissions"
  width={650}
/>
<DocsImage
  src="/img/cloud/integrations/github/ghe/ghe-04-pr.jpg"
  alt="Configure app permissions"
  width={650}
/>

5. Skip to the bottom of the form and click the **Create GitHub App** button.
   Your new GitHub App is now created, and you'll be taken to the settings page.

6. Returning to Cypress Cloud GitHub Enterprise Integration configuration
   screen, populate the following values from your new GitHub App.
   - Copy the root URL of your GitHub Enterprise site to the Cypress **GitHub
     Enterprise Server URL** field.
   - Copy the **App ID** to the Cypress **GitHub Enterprise App ID** field.
   - Copy the **Client ID** to the Cypress **GitHub Enterprise Client ID**
     field.
   - Copy the **GitHub App name** to the Cypress **GitHub Enterprise App name**
     field.
   - Generate a new Client secret in GitHub by clicking on the **Generate a new
     client secret** button. Copy the new secret into the Cypress **GitHub
     Enterprise Client secret** field.
   - Generate a new private key in GitHub by clicking on the **Generate a
     private key** button. Open in a text editor and copy all of the content
     into the Cypress **GitHub Enterprise Private key** field.

<DocsImage
  src="/img/cloud/integrations/github/ghe/ghe-05.jpg"
  alt="Collect new app info"
  width={700}
/>

<DocsImage
  src="/img/cloud/integrations/github/ghe/ghe-06.jpg"
  alt="Generate client secret"
  width={680}
/>

<DocsImage
  src="/img/cloud/integrations/github/ghe/ghe-07.jpg"
  width={645}
  alt="Generate private key"
/>

7. In Cypress Cloud, click the **Next Step** button, and you will be taken to
   the GitHub Enterprise app authorization page. Click the **Authorize \[your
   app name\]** button.

<DocsImage
  src="/img/cloud/integrations/github/ghe/ghe-08.jpg"
  width={700}
  alt="Authorize GitHub App"
/>

8. On your newly-authorized GitHub App, click the **Install** button.

<DocsImage
  src="/img/cloud/integrations/github/ghe/ghe-09.jpg"
  width={700}
  alt="Install GitHub App"
/>

9. Nearly there! On the GitHub App installation page, choose whether you want to
   install the app against all repos or select specific ones, then click the
   **Install** button.

:::info

All current and _future_ repositories will be included with this
installation if you choose **All repositories**.

:::

<DocsImage
  src="/img/cloud/integrations/github/ghe/ghe-10.jpg"
  alt="Confirm installation of GitHub App"
  width={535}
/>

10. Finally, you will be returned to Cypress Cloud. Congratulations, you have
    installed Cypress Cloud GitHub Enterprise integration! You are now ready to
    configure a GitHub Integration for a project.

:::info

If you are running the tests from within a restrictive VPN, see
[which subdomains to add to your allowlist for Cypress Cloud and your GitHub Enterprise integration to work properly](/cloud/faq#Im-working-with-a-restrictive-VPN-Which-subdomains-do-I-have-to-allow-on-my-VPN-for-Cypress-Cloud-to-work-properly).

:::

## Enabling GitHub integration for a project

After completing the Cypress GitHub App installation for your organization, you
can now enable GitHub Integration for _any_ Cypress project.

1. Go to the organization's Integrations page.

<DocsImage
  src="/img/cloud/organizations/navigate-to-organization-integrations.jpg"
  alt="Visit Organization's Integrations"
  width={600}
/>

2. Scroll down to the GitHub Integration or GitHub Enterprise Integration
   section.

:::info

You can quickly get to a project's GitHub Integrations settings by clicking on
the **Configure** link of the desired project within an
organization's Integrations page:

:::

<DocsImage
  src="/img/cloud/integrations/github/org-settings-with-no-enabled-projects.jpg"
  alt="Org GitHub Integration settings"
/>

3. Select a GitHub repository to associate with the project.

<DocsImage
  src="/img/cloud/integrations/github/project-settings-repo-selection.jpg"
  alt="Associate GitHub repo with Cypress project"
/>

Once a GitHub repository is associated with a Cypress project, the GitHub
integration will be immediately enabled:

<DocsImage
  src="/img/cloud/integrations/github/project-settings-selected-repo.jpg"
  alt="GitHub integration enabled for Cypress project"
  width={800}
/>

You can also see all GitHub Integration-enabled Cypress projects within your
organizations **Integrations** page:

<DocsImage
  src="/img/cloud/integrations/github/org-settings-with-projects.jpg"
  alt="Integrations page"
/>

## Status checks

If status checks are enabled within a project's GitHub integration settings,
Cypress Cloud will report Cypress test statuses to GitHub for related commits.
[Status checks](https://help.github.com/en/articles/about-status-checks) help
prevent merging a commit or pull request into the rest of your codebase until
all your Cypress tests have passed.

The Cypress GitHub App reports commit status checks in two distinct styles:

- **One check per
  [run group](/cloud/features/smart-orchestration/parallelization#Grouping-test-runs).**

  <DocsImage
    src="/img/cloud/integrations/github/status-checks-per-group.jpg"
    alt="Status checks per group"
  />

- **Or one check per spec file.**
  <DocsImage
    src="/img/cloud/integrations/github/status-checks-per-spec.jpg"
    alt="Status checks per spec"
  />

Each status check will report the number of test failures or passes, and the
associated **Details** link will direct you to the test run's page within
Cypress Cloud to help you dig deeper into the problem via error messages, stack
traces, screenshots, and video recordings:

<DocsImage
  src="/img/cloud/integrations/github/cloud-details-specs-tab.jpg"
  alt="Cypress Cloud specs tab"
/>

<TestReplayInfo />

### Disable status checks

GitHub status checks are optional and can be disabled within a project's GitHub
integration settings:

<DocsImage
  src="/img/cloud/integrations/github/status-check-settings.jpg"
  alt="Status checks settings"
/>

:::tip

<Icon name="star" /> **Premium Cypress Cloud Feature**

Reporting on flaky status checks is included in our
[Team, Business and Enterprise paid pricing plans](https://www.cypress.io/pricing).

:::

## Pull request comments

The Cypress GitHub App can provide detailed test information within the pull
requests via comments that include:

- **Run context details:**
  - The associated Cypress project
  - A link to the corresponding [Branch Review](/cloud/features/branch-review)
  - Run status (passed, failed, etc.)
  - Run duration
  - Commit message and SHA
  - Committer
- **Test results:**
  - Run statistics, such as tests passed, failed, skipped, flaky, and pending.
- **Tests for review:**
  - A summary of the tests that failed or are flaky
  - A link back to the associated failed or flaky test within Cypress Cloud

An example of a Cypress pull-request comment can be seen below:

<DocsImage
  src="/img/cloud/integrations/github/pr-comment-fail.jpg"
  alt="Cypress GitHub App PR comment"
  width={800}
/>

### Disable PR comments

PR comments are optional and can be disabled if not needed within a project's
GitHub Integration settings:

<DocsImage
  src="/img/cloud/integrations/github/pr-comments-settings.jpg"
  alt="Status checks settings"
/>

## Uninstall the Cypress GitHub app

You can uninstall the Cypress GitHub app from GitHub by performing the following
steps:

1. Go into your organization's **Settings** from within GitHub.
2. Click on **GitHub Apps**.
3. Click **Configure** beside the Cypress app.
4. Click **Uninstall** in the "Danger Zone" section.

## Troubleshooting

See
[Common GitHub Actions Problems and Solutions](/app/continuous-integration/github-actions#Common-Problems-and-Solutions).

## See also

- [Cypress GitHub Action + Examples](https://github.com/cypress-io/github-action)
- [Example project that uses both Cypress GitHub Action and Cypress GitHub Integration](https://github.com/cypress-io/gh-action-and-gh-integration)
